<!--
 ~ Copyright (C) 2015 CS SI
 ~
 ~ This program is free software; you can redistribute it and/or modify it
 ~ under the terms of the GNU General Public License as published by the Free
 ~ Software Foundation; either version 3 of the License, or (at your option)
 ~ any later version.
 ~ This program is distributed in the hope that it will be useful, but WITHOUT
 ~ ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 ~ FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
 ~ more details.
 ~
 ~ You should have received a copy of the GNU General Public License along
 ~ with this program; if not, see http://www.gnu.org/licenses/
 ~
-->
<html>
<head>
    <title>Standalone Tool Adapter</title>
    <link rel="stylesheet" href="../style.css">
</head>

<body>
<table class="header">
    <tr class="header">
        <td class="header">&nbsp;
            Standalone Tool Adapter
        </td>
        <td class="header" align="right"><a href="nbdocs://org.esa.snap.snap.help/org/esa/snap/snap/help/docs/general/overview/SnapOverview.html"><img src="../images/snap_header.jpg"
                                                                                     border=0></a>
        </td>
    </tr>
</table>

<h3>Operator structure</h3>
<p>Simply put, an adapter operator has the following folder structure:</p>
<p>
ADAPTER_FOLDER
<ul>
    <li>META-INF
        <ul>
            <li>MANIFEST.MF</li>
            <li>descriptor.xml</li>
        </ul>
    </li>
    <li>org
        <ul><li>esa
            <ul><li>snap
                <ul><li>ui
                    <ul><li>tooladapter
                        <ul><li>
                            layer.xml
                        </li></ul>
                    </li></ul>
                </li>
                    <li>utils
                        <ul><li>
                            ModuleInstaller.class
                        </li></ul>
                    </li>
                </ul>
            </li></ul>
        </li></ul>
    </li>
    <li>
        adapter-template.vm
    </li>
    <li>
        version.txt
    </li>
</ul>
<p>This folder should be copied in the location defined by <strong>user.module.path</strong> property in the configuration
file <strong>snap.properties</strong></p>
<h4>Quick Overview</h4>
<p>This is a listing of the elements directly under the descriptor's <b>operator</b> root element:</p>
<table>
    <thead>
        <tr>
            <th width="200px">XML Element</th>
            <th width="80px">Required</th>
            <th width="600px">Description</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td colspan="3" bgcolor="lightgray" style="padding-left:100px;"><strong>Operator descriptive parameters</strong></td>
        </tr>
        <tr>
            <td>name</td>
            <td>Yes</td>
            <td>The name of the adapter. Must be unique among the set of adapters.<br/>
                Sample value: <i>org.esa.snap.core.gpf.operators.tooladapter.MyAdapter</i>
            </td>
        </tr>
        <tr>
            <td>operatorClass</td>
            <td>Yes</td>
            <td>The implementing Java class.<br/>It is always <strong>org.esa.snap.core.gpf.operators.tooladapter.ToolAdapterOp</strong>
            </td>
        </tr>
        <tr>
            <td>alias</td>
            <td>Yes</td>
            <td>The alias of the adapter. This is should be the same as the name of the adapter folder.<br/>
                Sample value: <i>MyAdapter</i>
            </td>
        </tr>
        <tr>
            <td>label</td>
            <td>Yes</td>
            <td>The tag of the adapter. This will be used for creating the menu action for the adapter.<br/>
                Sample value: <i>My Adapter</i>
            </td>
        </tr>
        <tr>
            <td>version</td>
            <td>No</td>
            <td>The version of the adapter. Even though it is not mandatory, it is recommended to set it to a value.<br/>
                Sample value: <i>1.0.0</i>
            </td>
        </tr>
        <tr>
            <td>description</td>
            <td>No</td>
            <td>Descriptive text for the adapter.<br/>
                Sample value: <i>This is my first adapter</i>
            </td>
        </tr>
        <tr>
            <td>authors</td>
            <td>No</td>
            <td>The author(s) of the adapter.<br/>
                Sample value: <i>John Doe</i>
            </td>
        </tr>
        <tr>
            <td>copyright</td>
            <td>No</td>
            <td>Any copyright information of the adapter.<br/>
                Sample value: <i>(C)2015 Zulu</i>
            </td>
        </tr>
        <tr>
            <td>internal</td>
            <td>No</td>
            <td><i>Not used</i><br/>
                Possible values: <i>true</i>, <i>false</i>
            </td>
        </tr>
        <tr>
            <td>autoWriteSuppressed</td>
            <td>No</td>
            <td><i>Not used</i><br/>
                Possible values: <i>true</i>, <i>false</i>
            </td>
        </tr>
        <tr>
            <td>menuLocation</td>
            <td>Yes</td>
            <td>The menu path, in SNAP Desktop, where the action for the adapter will be placed. Value must be a valid NetBeans path.<br/>
                Sample value: <i>Menu/Tools/External Tools</i>
            </td>
        </tr>
        <tr>
            <td>source</td>
            <td>Yes</td>
            <td>Specifies if the adapter comes from a NBM module, or is created by the user.<br/>
                Possible values: <i>user</i>, <i>package</i>
            </td>
        </tr>
        <tr>
            <td>isHandlingOutputName</td>
            <td>No</td>
            <td>Specifies if the tool handles the output product name by itself. If <i>false</i>, <strong>targetProductFile</strong> has to be provided
                at execution time.<br/>
                Possible values: <i>true</i>, <i>false</i>
            </td>
        </tr>
        <tr>
            <td>isSystem</td>
            <td>No</td>
            <td><i>Deprecated</i>.<br/>
                Possible values: <i>true</i>, <i>false</i>
            </td>
        </tr>
        <tr>
            <td colspan="3" bgcolor="lightgray" style="padding-left:100px;"><strong>Pre-processing parameters</strong></td>
        </tr>
        <tr>
            <td>preprocessTool</td>
            <td>Yes</td>
            <td>Specifies if the adapter should execute another operator before its execution.<br/>
                Possible values: <i>false</i>, <i>true</i>
            </td>
        </tr>
        <tr>
            <td>writeForProcessing</td>
            <td>Yes</td>
            <td>Specifies if the input product of the adapter should be converted to another format before execution.<br/>
                Possible values: <i>false</i>, <i>true</i>
            </td>
        </tr>
        <tr>
            <td>processingWriter</td>
            <td>Yes</td>
            <td>Specifies to what format the input product of the adapter should be converted to.<br/>
                Possible values: <i>BEAM-DIMAP</i>, <i>CSV</i>, <i>ENVI</i>, <i>GeoTIFF</i>, <i>GeoTIFF-BigTIFF</i>,
                <i>HDF5</i>, <i>NetCDF-BEAM</i>, <i>NetCDF-CF</i>, <i>NetCDF4-BEAM</i>, <i>NetCDF4-CF</i>
            </td>
        </tr>
        <tr>
            <td colspan="3" bgcolor="lightgray" style="padding-left:100px;"><strong>Execution parameters</strong></td>
        </tr>
        <tr>
            <td>mainToolFileLocation</td>
            <td>Yes</td>
            <td>The path to the tool executable. Variables defined in the variables section can be used.<br/>
                Sample values: <i>C:\ToolBin\tool.exe</i>, <i>/usr/var/tool/bin/tool</i>, <i>$TOOL_PATH/$TOOL_BINARY</i>
            </td>
        </tr>
        <tr>
            <td>workingDir</td>
            <td>Yes</td>
            <td>The working directory. Variables defined in the <a href="#variables">variables</a> section can be used.<br/>
                Sample values: <i>C:\ToolBin\SomeFolder</i>, <i>/usr/var/wdir</i>, <i>$WORK_DIR</i>
            </td>
        </tr>
        <tr>
            <td>template</td>
            <td>Yes</td>
            <td>The path of the main Velocity template file, relative to the adapter folder. Should be on the same level as the META-INF directory.<br/>
                Sample value: <i>MyAdapter-template.vm</i>
            </td>
        </tr>
        <tr>
            <td>progressPattern</td>
            <td>No</td>
            <td>If specified, the regular expression to capture the progress from the tool output stream.<br/>
                Sample value: <i>(?:.+): (\d{1,3})% (?:.+)</i>
            </td>
        </tr>
        <tr>
            <td>errorPattern</td>
            <td>No</td>
            <td>If specified, the regular expression to capture tool errors from its output stream.<br/>
                Sample value: <i>ERROR: (.+)</i>
            </td>
        </tr>
        <tr>
            <td>numSourceProducts</td>
            <td>Yes</td>
            <td>The number of input source products. This is to be set in conjuction with the number of <a href="#srcProdDesc">DefaultSourceProductDescriptor</a> elements.<br/>
                Sample value: <i>1</i>
            </td>
        </tr>
        <tr>
            <td colspan="3" bgcolor="lightgray" style="padding-left:100px;"><strong>System variables</strong></td>
        </tr>
        <tr>
            <td>variables</td>
            <td>No</td>
            <td>See <a href="#variables">variables</a> section.
            </td>
        </tr>
        <tr>
            <td colspan="3" bgcolor="lightgray" style="padding-left:100px;"><strong>Operator parameters</strong></td>
        </tr>
        <tr>
            <td>parameters</td>
            <td>Yes</td>
            <td>See <a href="#parameters">parameters</a> section.
            </td>
        </tr>
    </tbody>
</table>
<h5 id="variables">Variables Section</h5>
<p>The element <strong>variables</strong> has one or more child elements <strong>variable</strong> (simple values) or <strong>osvariable</strong> (platform-dependent values):
    <table>
    <thead>
    <tr>
        <th width="200px">XML Element</th>
        <th width="80px">Required</th>
        <th width="600px">Description</th>
    </tr>
    </thead>
    <tbody>
    <tr>
        <td colspan="3">variable</td>
    </tr>
    <tr>
        <td style="padding-left:20px;">key</td>
        <td>Yes</td>
        <td>The variable key (or name). This value can be used as indicated above by prefixing the key with <strong>$</strong><br/>
            Sample value: <i>BIN_PATH</i>
        </td>
    </tr>
    <tr>
        <td style="padding-left:20px;">value</td>
        <td>Yes</td>
        <td>The variable value. If the variable represents an OS environment variable, the value element can be empty (the OS value will be read at run-time).<br/>
            Sample value: <i>/usr/var/tool/bin</i>
        </td>
    </tr>
    <tr>
        <td colspan="3">osvariable</td>
    </tr>
    <tr>
        <td style="padding-left:20px;">key</td>
        <td>Yes</td>
        <td>The variable key (or name). This value can be used as indicated above by prefixing the key with <strong>$</strong><br/>
            Sample value: <i>BIN_PATH</i>
        </td>
    </tr>
    <tr>
        <td style="padding-left:20px;">windows</td>
        <td>Yes</td>
        <td>The Windows-specific value.<br/>
            Sample value: <i>C:\Program Files\Tool\bin</i>
        </td>
    </tr>
    <tr>
        <td style="padding-left:20px;">linux</td>
        <td>Yes</td>
        <td>The Linux-specific value.<br/>
            Sample value: <i>/usr/var/tool/bin</i>
        </td>
    </tr>
    <tr>
        <td style="padding-left:20px;">macosx</td>
        <td>Yes</td>
        <td>The Mac OSX-specific value. May be similar to the Linux one.<br/>
            Sample value: <i>/usr/var/tool/bin</i>
        </td>
    </tr>
    </tbody>
</table>

<h5 id="parameters">Parameters Section</h5>
<p>The element <strong>variables</strong> has one or more child elements <strong>parameter</strong> with the following structure:</p>
<table>
    <thead>
        <tr>
            <th width="200px">XML Element</th>
            <th width="80px">Required</th>
            <th width="600px">Description</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td>name</td>
            <td>Yes</td>
            <td>The parameter name. This value can be used in templates by prefixing the key with <strong>$</strong><br/>
                Sample value: <i>inputFile</i>
            </td>
        </tr>
        <tr>
            <td>alias</td>
            <td>No</td>
            <td>The parameter alias.<br/>
                Sample value: <i>in</i>
            </td>
        </tr>
        <tr>
            <td>alias</td>
            <td>No</td>
            <td>The parameter alias. In a future version this will be the command line flag of the parameter.<br/>
                Sample value: <i>in</i>
            </td>
        </tr>
        <tr>
            <td>dataType</td>
            <td>Yes</td>
            <td>The parameter type. Can be one of the following:<br/>
                <ul>
                    <li><i>Boolean</i>: <strong>defaultValue</strong> may be <i>true</i> or <i>false</i></li>
                    <li><i>Integer</i>: <strong>defaultValue</strong> may be an integer</li>
                    <li><i>Decimal</i>: <strong>defaultValue</strong> may be a float</li>
                    <li><i>String</i>: <strong>defaultValue</strong> may be a text value</li>
                    <li><i>File</i>: <strong>defaultValue</strong> may be a File object</li>
                    <li><i>List</i>: <strong>defaultValue</strong> may be list of string values</li>
                    <li><i>TemplateBeforeExecution</i>: <strong>defaultValue</strong> should be the name of the before-execution Velocity template</li>
                    <li><i>TemplateAfterExecution</i>: <strong>defaultValue</strong> should be the name of the after-execution Velocity template</li>
                </ul>
            </td>
        </tr>
        <tr>
            <td>defaultValue</td>
            <td>No</td>
            <td>The parameter default value.<br/>
                Sample value: see the above element.
            </td>
        </tr>
        <tr>
            <td>valueSet</td>
            <td>No</td>
            <td>For all types except File or List, this specifies the set of accepted values for the parameter. The values are specified by <strong>string</strong> child elements.<br/>
                Example: for an Integer data type, the valueSet elements would have the children:<br/><i>< string>1< /string>< string>2< /string>< string>3< /string></i>
            </td>
        </tr>
        <tr>
            <td>notNull</td>
            <td>Yes</td>
            <td>Specifies if the parameter's defaultValue can be null.<br/>
                Possible values: <i>true</i> or <i>false</i>
            </td>
        </tr>
        <tr>
            <td>notEmpty</td>
            <td>Yes</td>
            <td>Specifies if the parameter's defaultValue can be empty.<br/>
                Possible values: <i>true</i> or <i>false</i>
            </td>
        </tr>
        <tr>
            <td>parameterType</td>
            <td>Yes</td>
            <td>Specifies the type of the parameter.<br/>
                Possible values: <i>RegularParameter</i>, <i>FolderParameter</i>, <i>TemplateParameter</i>, <i>TemplateBeforeExecution</i>, <i>TemplateAfterExecution</i>
            </td>
        </tr>
    </tbody>
</table>
<h5 id="srcProdDesc">Source Products Descriptors section</h5>
<p>The element <strong>sourceProductDescriptors</strong> has one or more child elements <strong>org.esa.snap.core.gpf.descriptor.DefaultSourceProductDescriptor</strong> with the following structure:</p>
<table>
    <thead>
        <tr>
            <th width="200px">XML Element</th>
            <th width="80px">Required</th>
            <th width="600px">Description</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td>name</td>
            <td>Yes</td>
            <td>The conventional name of the source product name. The convention is <strong>sourceProduct.n</strong> where <strong>n</strong> is the product number<br/>
                Sample value: <i>sourceProduct.1</i>
            </td>
        </tr>
    </tbody>
</table>
<p>Please remember that the number of <strong>org.esa.snap.core.gpf.descriptor.DefaultSourceProductDescriptor</strong> elements should match the value of the <strong>numSourceProducts</strong> element</p>
</body>
</html>
